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Introduction 


The Microsoft® Professional Advisor Library Reference contains information 
about the help library supplied with Microsoft C products. There are several 
advantages to using the Advisor Help Library. 


Speed and Maneuverability The help desired by the user must be 
available quickly, with a minimum of user decisions and selections. To achieve 
this goal, the Advisor Help Library supports cross-referencing, context sensitiv- 
ity, preserves previous help activity, and flexible help-text organization. 


Modification Users and/or application developers need to be able to add help 
text to the help system and modify existing help text to suit their applications and 
environments. To meet this need, a maintenance utility performs both compres- 
sion and decompression of help files. Also, the Advisor Help Library provides 
the ability to read uncompressed ASCII text as a help file. 


Integration The help text presented must be available to outside applications. 
The Advisor Help Library provides support routines necessary to allow the appli- 
cation to access this valuable help text. 


Size It is important to create help files that take up minimal disk space but 
do not at the same time severely impact look-up speed. The Advisor Help 
Library provides three compression algorithms to reduce disk space and meet 
speed requirements. 


The Advisor Help Library includes the following files: 


File Name Description 

HELPMAKE.EXE Bound Help-File-Maintenance Utility. 
MSHELP.DLL OS/2 help engine in DLL form. 

MSHELP.LIB OS/2 help engine export library. 

MHELP.LIB Medium-model help engine. 

MHELPH.LIB Medium-model help engine using handle:offset. 
LHELP.LIB Large-model help engine. 
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WHELPP.LIB SS!=DS help engine, protected mode. 

WHELPR.LIB SS!=DS help engine, real mode. 

HELP.H Help engine include file. All applications should 
use this. 

MSHELP.DEF .DEF file for applications that can use it. 

SHELP.LIB Small-model help engine. 


NOTE The pages that follow use the term “OS/2” to refer to the OS/2 systems—Microsoft 
Operating System/2 (MS@ OS/2) and IBMe OS/2. Similarly, the term “DOS” refers to both 
the MS-DOS® and IBM Personal Computer DOS operating systems. The name of a specific 
operating system is used when it is necessary to note features that are unique to the system. 


CHAPTER 
The Help Database 


There are four types of format text for the topical contents of the help database: 


ASCII Format _ Description 

QuickHelp Default source format for compressed databases 

Minimally formatted Can be either compressed or read directly from the 
help engine 

RTF An alternate source for the compressed database 

Unformatted For use directly by the help engine 


1.1. QuickHelp ASCII 


QuickHelp uses “dot” commands and embedded formatting characters to convey 
information to HELPMAKE. For example: , 


-context 


Each topic is preceded by one or more .context commands that indicate the con- 
text string for the following topic text up to the next .context line. More than one 
context command may be specified for a single topic, if no topic text is placed 
between them. For more information on topic commands, see Section 2.3 in 
Chapter 2, “Text Structure and Conventions.” 
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1.1.1 Formatting Flags 


The following flags may be embedded in the text to change the attributes of the 


topic text: 

Formatting Flag Action 
\b or \B Bold 

\i or I Italic 

\p or \P Plain 

\u or \U Underline 
\v or \V Invisible 


The flags \b, \i, \u and \v are toggles, turning on and off their respective attribute. 
They may be combined. The \p flag turns off all attributes. 


The backslash character also escapes the character which follows it, that is, 
\b 

indicates the toggling of the bold attribute, while 

Wb 

places a “\b” into the actual text. 


Lines are truncated to the specified width in characters (which defaults to 76); 
flags affecting the attribute do not count towards the 76-character limit. When 
“/T” is specified, lines beginning with the specified application’s control charac- 
ter or “.” are truncated at 255, regardless of the width specification. 


1.1.2 Cross-References 


Cross-references are embedded in one of two ways: 


1. Invisible text, immediately following a space-delineated word, generates 
a cross-reference whose text is the invisible text and whose hotspot is the 
entire word. 


2. An anchor, signified by “\a”, followed by normal text, which is then fol- 
lowed by invisible text, generates a cross-reference whose text is the invisible 
text and whose hotspot is all text between the anchor and the beginning of the 
invisible text. 


The Help Database 3 


1.1.3 QuickHelp Example 


The following is an example of a help database containing a single entry using 
QuickHelp format: 


.context #define 

Syntax: #define <identifier> <substitution-text> 
#define <identifier> [(<parameter-list>)] 
<substitution-text> 


Replaces all subsequent cases of \bidentifier\p with the 
substitution-text. If \bparameter-list\p is given after 
\bidentifier\p, each occurrence of \bidentifier\p 
(\bparameter-list\p) is replaced with a version of 
\isubstitution-text\p modified by substituting actual 
arguments for formal parameters. 


1.2 Minimally Formatted ASCII 


Uncompressed, minimally formatted ASCII help files can be used at run time at 
the cost of slower searches and larger help files. Unformatted ASCII files are a 
fixed width and may not contain highlighting or cross-references. 


The help file is a sequential series of topics, each preceded by one or more 
unique context definitions. Each context definition should be on a line of its own, 
beginning with “>>.” Subsequent lines up to the next context definition consti- 
tute the topic text. For example: 


>>#define 


Syntax: déedefine <identifier> <substitution-text> 
#define <identifier> [(<parameter-list>)] 
<substitution-text> 


Replaces all subsequent cases of identifier with the 
substitution-text. If parameter-list is given after identifier, 
each occurrence of identifier (parameter-list) is replaced with 
a version of substitution-text modified by substituting actual 
arguments for formal parameters. 


The minimally formatted ASCII help file must begin with “>>.” Since the first 
topic in such a database must start with a context definition line anyway, this 
allows for limited error checking to ensure that the referenced file is indeed an 
ASCII help file. 


Minimally formatted ASCII files do not support non-default attributes or 
cross-references. 
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1.3 Unformatted ASCII 


Fully unformatted ASCII files may be cross-referenced by other help files. 
When referenced, the entire ASCII file is treated as a single help topic. No for- 
matting information may be present in such a file, and color may not be used. 
The file is returned by the help engine “as is.” Such a file has no physical “next” 
or “previous.” : 


1.4 RIF ASCII 


In this format, the database is formatted in a subset of RTF to support special 
attributes. RTF syntax outside of the understood subset is ignored and stripped 
out by HELPMAKE. RTF generated by other programs such as Microsoft 

Word 4.x, Microsoft Word for the Apple@ Macintoshe, or Word-RTF can be 
used directly. This allows help authors to write and format directly in these word 
processors. 


HELPMAKE recognizes the subset of RTF listed below: 


RTF Code Action 

\plain Reset to default attributes. On most screens this is 
unblinking normal intensity. 

\b Bold. This is displayed as intensified text. 

\i Italic. Displayed as reverse video. 

\v Hidden text. Hidden text is used for cross-reference 


information and some application-specific com- 
munications, and is not displayed. 


\ul | Underline. Represented as blue text on adapters 
which do not support underlining. 

\par End of paragraph. 

\pard Reset paragraph formatting to defaults. 

\fi Paragraph first line indent. 

\li | Paragraph left indent. 

\line New line (not new paragraph). 


\tab Tab character. 
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Topics may be paragraph-broken. HELPMAKE formats the text toa fixed width 
at compression time. 


Each entry in the database source consists of one or more context strings, fol- 
lowed by topic text. The sequence “>>” at the beginning of any paragraph de- 
notes the beginning of a new help entry. Subsequent text within that paragraph 
constitutes the keyword. If the immediately following paragraph begins with 

>>,” it also defines a context string for the same topic text. Subsequent para- 
graphs, up to the next paragraph beginning with “>>”, constitute the topic text 
associated with those contexts. 


1.4.1 RIF Example 


The following is an example of a help database containing a single entry using 
minimal RTF text: 


{\rtf@ 

>> #define \par 

Syntax:\tab #define <identifier> <substitution-text> 

\par 

\tab #define <identifier>[(<parameter-list>)] <substitution-text> \par 
\par 

Replaces all subsequent cases of {\b identifier} with the substitution-text. 
If {\b parameter-list} is given after {\b identifier}, each occurrence of 
{\b identifier} ({\b parameter-list} ) is replaced with a version of 

{\i substitution-text} modified by substituting actual arguments for formal 
parameters. \par 


J 
The result, referenced by the context string #define: 


Syntax: #define <identifier> <substitution-text> 
#define <identifier>[(<parameter-list>)] <substitution-text> 


Replaces all subsequent cases of identifier with the substitution-text. If 


Darameter-list is given after identifier, each occurrence of identifier 
(parameter-list) is replaced with a version of substitution-text modified by 
substituting actual arguments for formal parameters. 


Note that the bold attributes in this example are shown as underline. 
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1.4.2 Local Contexts 


In RTF, QuickHelp, and minimal ASCII formats, certain context strings may be 
defined as local contexts, being “local” to the help file. Then these context 
strings may not be looked up by HelpNc, but instead may be used only as the 
target of embedded cross references in the text. 


Local contexts are encoded just like normal contexts, except that they begin with 
the at-sign character (@). The actual strings following the at sign are discarded 
by HELPMAKE during compression. Cross-references to local contexts are then 
encoded in the help file in a more compact form. 


Local contexts provide the following advantages: 


Space savings. The context strings are not preserved and hence are not carried 
in the help file’s context string table. Cross-references to local contexts do 
not reference the actual context string, but instead are encoded in a smaller, 
3-byte format. 


Access restriction. You cannot mistakenly ask for help on what would be a 
local context string. 


The following restrictions also apply: 


Local contexts must be resolvable within a single help file. HELPMAKE pro- 
duces warnings if a local context is cross-referenced, but never defined in the 
help file being created. 


Topics which are the targets of local contexts can be accessed in only two 
ways: as the target of a cross-reference or by physical or historical relative 
movement in the help file (Next, Previous, or Back). 


For example: 


.context normal 

This is a normal topic, accessible by the context string 
“normal.” [Lbutton\v@local\v] is a cross-reference to the 
following topic. 


-context @local 

This topic can be reached only by physical previous or next, a 
historical backup, or by the cross-reference in the previous 
topic. 
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1.5 Physical Database Organization 


The physical database consists of several pieces, as outlined below: 


| Topic Index 
+------ 
| Context Strings 


| Keyphrase Table 
+----- 

| Huffman Decode Tree 
+----- 

| Compressed Topic Text 
aim inn 


| File Title 
+—---- 


Help files may also be concatenated together so that the above pattern is 
repeated. For example, 


COPY FOO.HLP/B + BAR.HLP/B + YOU.HLP/B MONDO.HLP/B 


This command creates a single help file called MONDO.HLP, which consists of 
the three component help files: FOO, BAR, and YOU. This file, when opened by 
the help engine, counts as three files against the engine’s open file limit. In most 
other respects, it acts exactly like a single help file. 


1.5.1 Concatenated Order 


The next several sections explain the pieces in the order in which they physically 
appear in a concatenated help database. 


Header Identifies the help file and contains data relating to the content of the 
file. It is described by the following C structure: 
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typedef struct { 


ushort wMagic; 
ushort wSignature; 
ushort wFlags; 
ushort appChar; 
ushort cTopics; 
ushort cContexts; 
ushort cbWidth; 
ushort cPreDef; 
uchar fname[14]; 
ushort reserved([2]; 
ulong posTb1[9]; 
ulong fsize; 

} header; 


where the following information is called out by the left-hand column: 


Header Data Description 

wMagic A word that identifies this as a help file. 

wSignature A word that identifies the “owner” or application 
\ that uses this help file. 

wFlags A word that contains the following flags: 


Bit Action 
0 Set if context look-up is to be case sensitive. 


1 Set if the file is locked and cannot be 
decompressed. 


appChar Application-specific character, controlling access to 
certain line of help text. (See the /A parameter to 
HELPMAKE.) Oxff if not set. 


cTopics A count of entries in the topic index. 
cContexts A count of context strings. 


cbWidth The fixed width encoded by HELPMAKE, if one 
was specified. If zero, the data must be formatted to 
the display width by the application. 


cPreDef Count of predefined contexts. 


fname The original file name created by HELPMAKE. 
This is used to identify individual help files which 
have been concatenated into larger help files. 
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posTbl A table of file positions for the various fields in the 
database: 


File Position Description 


0 File offset of the topic index. 

1 File offset of the context strings. 

2 File offset of the context map. 

5 File offset of the keyphrase table; 
0 if keyphrase compression was 
not performed. 

4 File offset of the Huffman decode 
tree; 0 if Huffman encoding was 
not performed. 7 

2 eg File offset of text of the first topic. 
File offset of file title. 

7-8 Reserved. 

9 Size of help file in bytes. 


Topic Index A table of file positions for each topic contained in the help file. 
Topic #n’s file position can be found in the nth entry in this table. In addition, 
the size in bytes of any compressed topic can be determined by the difference 
between two successive file positions. 


Context Strings An array of strings which map to context numbers in the fol- 
lowing context map. These strings are used for topic look-up when no predefined 
context number has been assigned. 

Context M ap A mapping of context numbers to topic numbers. This allows 
context numbers to be somewhat arbitrarily assigned, by an outside piece of 
software, such as a parser, and then mapped to sequential topic numbers. 
Keyphrase Table Table of strings used in keyphrase decompression. 
Huffman Decode Tree The tree used to decompress Huffman encoded data. 


Compressed Topic Text The compressed text for the actual topic data, 
preceded by a 1-word count of bytes in the uncompressed topic. 


File Title The title or name specified with the /N command at compression 
time. 
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1.5.2 Decompressed Topic Format 


Each line of the decompressed topic is formatted as follows: 


$-------- $---------------------- +: 


! cbText | ASCII Text 
--------- $-----4--4+----------------+ 


! cbInfo | Attr Info 
ee ee fam ee ae ae ee ee ee ee ee et 


| Offffh | Cross-Ref Info | 


Topic information appears in the following order: 


Topic Data 


cbText 


ASCII Text 


cbInfo 


Attr Info 


Description 


Byte. Length in bytes, plus one, of the ASCII text 
which follows. 


Text of the line. All characters are displayable. 
CR-LF characters have no special meaning. 


Word. Length in bytes plus two of the attribute and 
cross-reference information that follows. 


Information describing the attributes associated with 
the preceding line. These are formatted as attribute 
index/byte-count-byte pairs with attribute Offh indi- 
cating the end. 


Attribute indexes are bytes whose bits represent the 
following attributes: 


Bit Attribute 


0 Bold 
1 Italic _ 
2 Underline 


Thus, attribute indexes can range in value from 0-7, 
representing various combinations of the above. 
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Cross-Ref Info Definition of the “hotspots” contained in the line 
and what they cross-reference to. Each hotspot is 
formatted as: 


$-ptenatenn--- Slate + 
| cols | cole | cross=reT | 
+------ $------ Hoan neon nn-- + 


where format information breaks down as follows: 


Definition Description 

cols Byte. Starting column of hotspot. 

cole Byte. Ending column of the 
hotspot (inclusive). 

cross-ref ASCIZ string. Context which the 


hotspot cross-references to. Either 
a null-terminated ASCII string or a 
“local context” (a 3-byte internal 
data structure, the first byte of 
which is zero). 


1.6 The Encoding Process 


The HELPMAKE utility makes several passes on the data when encoding source 
files into help-file format. The amount of compression to be performed is op- 
tional and is specified when HELPMAKE is run. 


HELPMAKE passes are described below. 


1. In the first pass, extraneous encoding information is stripped from the file and 
remaining formatting information is converted to an internal form. Local con- 
text references and definitions are collected. 


2. During the second pass, local context references are resolved. If enabled, the 
text is also run-length encoded. All runs of 4 to 255 identical characters are re- 
placed with a flag, the character, and a repetition count. During this pass the 
context strings are collected. If keyphrase compression is enabled, the en- 
coded text 1s analyzed for keyword/phrase frequency. 


3. If keyphrase compression is enabled, the following pass replaces all space- 
saving occurrences of keyphrases with a flag byte and a byte index. If Huff- 
man encoding is enabled, character frequency of the output is analyzed for 
Huffman tree construction. 
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4. If Huffman encoding is enabled, a following Huffman pass encodes the topic 
text. | 


5. The next-to-last pass builds file topic and compression tables in their final 
form in preparation for writing to the output file. 


6. In the final pass, the actual help file is written. The help-file header, topic 
index, context string table, context map, keyphrase table, and Huffman tree 
are all written to the help file, followed by the compressed topic text. 


As noted above, once compressed, multiple help files can be manually 
concatenated to produce single help files. 


CHAPTER 


Text Structure 
and Conventions 


Common structures and conventions ensure that help files for one application 
will make sense when viewed using another. This information goes beyond the 
context-string and topic-text mapping functions of the help engine itself. This 
chapter outlines organizational conventions and approaches that should be fol- 
lowed by applications that provide maximally cross-compatible help files. 


2.1 Authoring the Help Database 


The help engine is a data-retrieval tool that imposes no real restrictions on the 
content and format of the help text. The HELPMAKE utility and additional dis- 
play routines and conventions, however, make certain assumptions about the for- 
mat of help text. This section provides some help authoring guidelines. 


2.1.1 QuickHelp Format 


When using QuickHelp format, a text editor would be used. QuickHelp format 
also lends itself to relatively easy automated translation from other document 
forms. 


Help text source is a sequential series of topics, each preceded by one or more 
unique context definitions. In QuickHelp format, each topic begins with one or 
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+ 


more “context” lines defining the context strings which map to the topic text. 
Subsequent lines up to the next “.context” constitute the topic text. For example: 


.context #define 

Syntax: #define <identifier> <substitution-text> 
ddefine <identifier> [(<parameter-list>)] 
<substitution-text> 


Replaces all subsequent cases of \bidentifier\p with the 
substitution-text. If \bparameter-list\p is given after 
\bidentifier\p, each occurrence of \bidentifier\p 
(\bparameter-list\p) is replaced with a version of 
\isubstitution-text\p modified by substituting actual arguments 
for formal parameters. 


See Chapter 1 for a detailed discussion of QuickHelp. 


2.1.2 RIF Format 


When using RTF format, authoring can take place using a word processor 

or other tool capable of generating RTF output. Mac WORD, Microsoft 
Word 4.x, and Word-RTF (a tool that converts Word format files to RTF) are 
all alternatives. 


In RTF, each context definition should be in a paragraph of its own, beginning 
with “>>.” Subsequent paragraphs up to the next context definition constitute the 
topic text. For example: 


{\rtf@ 

>> #define \par 

Syntax:\tab #define <identifier> <substitution-text> 

\par 

\tab #define <identifier>[(<parameter-list>)] <substitution-text> \par 

\par 

Replaces all subsequent cases of {\b identifier} with the substitution-text. 
If {\b parameter-list} is given after {\b identifier}, each occurrence of 
{\b identifier} ({\b parameter-list} ) is replaced with a version of 

{\i substitution-text} modified by substituting actual arguments for formal 
parameters. \par 


} 


In these examples, the context string #define relates to the topic text which 
follows it. The topic text contains embedded bold and italic text. See Chapter 1 
for a detailed discussion of RTF format. 


Text Structure and Conventions 15 


2.2 Hotspots and Cross-References 


Cross-references are included as invisible text. A word or an anchored phrase, 
known as a hotspot, followed by invisible text, constitutes a cross-reference. For 
example: 


-context EXE2BIN 
EXE2BIN 


Convert .EXE file to Binary-Image File 
\bPurpose\b 


Converts an executable file in the .EXE\vexe_format\v format to a 
memory image file in binary format. The EXE2BIN utility is supplied 
with the MS-DOS distribution disks. 


In this example, the word “.EXE” in the first line of the paragraph is the hotspot. 
It cross-references to “exe_format.” A mouse click or other form of selection 
with the cursor on any of the letters of “EXE” brings up the help topic whose 
context was “exe_format.” The invisible text “exe_format” is not actually 
displayed. 


When the desired hotspot crosses more than one word, an anchor is used: 


Converts an executable file in the \a.EXE format\vexe_format\v 
to a memory image file in binary format. The EXE2BIN utility is 
supplied with the MS-DOS distribution disks. 


In this case, the hotspot consists of the entire phrase ““.EXE format.” Anchored 
hotspots must be contained on a single line. 


The invisible cross-reference text is formatted as one of the following: 


Text Command Action 
context_string Results in the help topic associated 


with the arbitrary context string being 
displayed. For example, “exe_for- 
mat” results in the help topic as- 
sociated with that context being 
displayed. 


@context_string Causes the help topic associated with 
the local context string to be dis- 
played. As defined in a previous sec- 
tion, local contexts must be defined 
in the same help file that they are ref- 
erenced in. 
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filename! Causes the entire file referenced to 
be treated as a single topic to be dis- 
played. For example, the command 
“SINCLUDE:stdio.h!” would search 
the INCLUDE environment variable 
for STDIO.H, and display it as a 
single help topic. 


filename!context_string Same as “context_string” above, ex- 
cept that only the help file “filename” 
is searched. If not already open, it is 
searched for, either on the path or 
explicit environment variable, and 
opened. For example, the command 
“SINIT:mep.hip!assign” would 
search for “mep.hlp” on the INIT en- 
vironment variable, and bring up the 
topic associated with “assign.” 


'cmd A cross-reference command. These 
commands are discussed in Section 
2.4. 


2.3 Topic Commands 


Topic commands embedded into the help text provide additional control informa- 
tion to the application displaying help. The commands are contained on a single 
line which is not considered part of the help text, and is not displayed to the user, 
but is embedded into the help text source. 


With the exception of “.context” and “.comment,” topic commands take two 
forms: an “English” version used in the help source code (dot command), and a 
shortened version actually placed in the encoded help file and understood by the 
application displaying help (colon command). English versions of the commands 
are automatically converted by the HELPMAKE program to the single character 
versions (or back) on encode (or decode). 


Note that “:” is replaced by whatever application-specific character is specified 
to HELPMAKE using the /A parameter. Applications writers should support 
only the “:” commands listed below. Help-file authors should be concerned with 
only the English “.” forms of the commands discussed in Table 2.1. 
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Table 2.1 HELPMAKE Topic Commands 


Command Action 
«context context string Required. 
category string number _ Contains the category name the current function is in, 


scstring number 


command 
°X 


comment text 


execute cmd 
sycmd 


and its position in the list of functions. The .category 
name is used by the QuickHelp Topic command, which 
brings up the list of topics that the current topic is part of. 
This is done by fetching the category name, which is a 
list-type topic, and finding where the current topic is 
within the list of topics. 


If the help topic being displayed at the time of a request 
is for “‘h.contents” (the table of contents), applications 
may divert the search to the .category string of the cur- 
rently displayed topic. 


The .category command, if present, must precede all dis- 
playable help text. If not supported by an application, this 
command should be ignored. 


Indicates that the topic text is not a displayable help 
topic, and should not be displayed to the user. Used to 
precede script topics, and other internal information. 


The .command command, if present, must precede all 
displayable help text. Should be supported by all applica- 
tions. (If a next or previous operation encounters a topic 
containing this command, the topic should simply be 
skipped.) : 


Used in the source file to specify a comment line which 
will not be placed into the database (i.e., HELPMAKE re- 
moves this line). This is used by help authors to comment 
their source code so that it can be maintained by other 
authors without having the text go into the database. This 
can be particularly valuable when documenting cross- 
references that have commands (i.e., you can insert a 
comment and say what the cross-reference is supposed 
to do). 


Since the comments are not preserved in the compressed 
file, they cannot be restored via decompression. 


Executes the specified cross-reference command. This 
command is executed at the time the line is encountered 
while the application is processing the topic for display. 
All cross-reference commands are valid, even though not 
all make sense. This command may appear anywhere in a 
topic. 


If not supported by an application, this command should 
be ignored. 
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Table 2.1 


e 


HELPMAKE Topic Commands (continued) 


Command 


Action 


file filename 
sffilename 


freeze ## 
oz HH 


mark text [##] 
emtext [##] 


list 


next context string 
:>context string 


Normally used by an internal release of the database to 
point to the location of the source file. The private build 
of QuickHelp along with a macro command in MEP 
can make it possible to load the source file with two 
keystrokes. 


If not supported by an application, should be ignored. 


Indicates that the next ## lines which follow are to be 
“frozen” as the top line(s) on the help screen. This is typi- 
cally used to freeze a row of cross-reference buttons at 
the top of a help topic which might be scrolled. 


The .freeze command, if present, must precede all dis- 
playable help text. If not supported, should be ignored. 


Defines a “mark” immediately preceding the following 
line of text. An optional number, indicating column loca- 
tion, may also be included. Can be referenced by Advisor 
Script commands (see Section 2.4), usually to indicate 
that display of a particular topic begins at the marked 
line, rather than the first line. 


-mark names are unique (local) to each topic. If not sup- 
ported by an application, should be ignored. 


Specifies the initial length of the topic when displayed. 
Applications that can resize the window in which help is 
displayed should attempt to resize so that # number of 
lines are displayed. 


The .length command, if present, must precede all dis- 
playable help text. If not supported by an application, 
should be ignored, and the application must support a rea- 
sonable default window or screen size. 


Indicates that the current topic contains a list of topics. 
This will cause a highlighted line to be displayed. You 
can select a topic by moving the highlighted line over the 
desired topic, and then pressing the ENTER key. The first 
word of the line will be used as the topic string to search 
for. 3 


If not supported by an application, the topic should 

be displayed as any other help topic (i.e., .list can be 
ignored). 

Indicates that the physically next topic should be looked 
up using the supplied context string, rather than getting 
the actual next topic. This is used to skip large blocks of 
command or .popup topics quickly. 

The .next command, if present, must precede all displaya- 
ble help text. 
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Table 2.1 HELPMAKE Topic Commands (continued) 


Command Action 


-previous context string Tells the help system to look up the physically previous 

:<context string topic using the supplied context string rather than get the 
actual previous topic. This is used to skip large blocks of 
command or .popup topics quickly. 


paste paste-name Begins a paste section, with the name appearing in Quick- 
:ppaste-name Help’s Paste menu. If not supported by an application, 
should be ignored. 
The .paste command, if present, must precede all display- 
able help text. 
end Ends a paste section. If not supported by an application, 
e this command should be ignored. 
-popup Indicates to QuickHelp that the current topic is not to be 
4 loaded as a normal, scrollable topic. Instead the number 


of lines in the current topic is counted, and a box is 
created with the topic displayed within it. As soon as you 
press a key or click the mouse button, the popup box will 
go away. If you have already loaded QuickHelp, the pre- 
vious topic is displayed. 

When QuickHelp is first run, it attempts to find a topic 
from the word underneath the cursor. If that topic is a 
popup topic, QuickHelp displays the popup box, then re- 
turns without displaying its main window. 

The .popup command, if present, must precede all dis- 
playable help text. If not supported by an application, the 


topic can be displayed normally. 
ref [string], [string], ... Contains a list of comma-separated topics (i.e., functions 
sr[string], [string], ... and structures) that appear in the Reference menu, and 


will be preloaded by the PreLoad thread. If not supported 
by an application, this command should be ignored. 


topic topic name If not supported by an application, this command should 
sntopic name be ignored, and no title or name displayed. 


2.4 Cross-Reference Commands 


Cross-reference commands extend hotspots beyond simply moving around in 
help information. These commands actually carry out actions in response to user 
selection. 


Typically, when a hotspot is selected by the user of the help system, the as- 
sociated invisible text or “cross-reference” is simply “looked-up” as another help 
request, and its associated topic displayed. A cross-reference command (usually 
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prefixed by an exclamation point) contains instead an instruction to be carried 
out by the host application. 


The executable command, or in some cases the command class, is defined by its 
first character. Uppercase alphabetic and special character commands are broadly 
classified as “Advisor Script Commands,” and potentially applicable to all help 
systems. Lowercase characters are used to define commands or command classes 
of restricted applicability. 


These commands are discussed in Table 2.2. 
Table 2.2 HELPMAKE Cross-Reference Commands 


Command Class 


>string Indirection. The rest of the command is a context string which 
should be looked up, and whose topic contents should be executed, 
line by line, as a series of Advisor Script Commands. Such a topic is 
referred to as a script topic. The initial exclamation point is not pre- 
sent on the commands contained within a script topic. 


space The rest of the command string should be executed visibly by the 
operating system. For example, “! DIR” causes the operating system 
to print the contents of the current directory. 


{ The rest of the command string should be executed invisibly by the 
operating system. For example, “!!COPY FILEA FILEB” causes the 
operating system to copy FILEA to FILEB, with no visible output. 


B Back. The application is to redisplay the previously viewed help 
topic. May be ignored if the historical backtrace list is exhausted, or 
if historical backtrace is not supported by the application. 


Cc Context. The rest of the command string is a context string to be re- 
trieved and immediately displayed. (Intended for use within script 
topics.) This is equivalent to a traditional cross-reference that does 
not begin with a “!.” 

D Delay. The rest of the command string is an ASCII encoded number, 
which is the number of tenths of a second to delay. When executed, 
the application simply delays that much time before continuing. (In- 
tended for use within script topics.) 


Hsx/,y1,x2,y2 Highlight. The rest of the command specifies a region, and a 
highlighting state ‘‘s” is replaced by either “E”’ to enable highlighting 
on the region, or “—” to disable. The highlighted region is from the 
upper left corner specified by (x/,y/) to the lower right corner 
specified by (x2,y2). All coordinates are one-based. The actual visual 
effect of highlighting is left up to the application; however, reverse 
video is the commonly accepted result. 


K Wait for any keystroke before proceeding. 


Kkey Wait for specific keystroke before proceeding; “key” is replaced by 
the key name. Beep until correct key is entered. 
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Table 2.2.9 HELPMAKE Cross-Reference Commands (continued) 


Command Class 

Kkey text Wait for specific keystroke before proceeding; “key” is replaced by 
the key name. Display “text” if wrong key is entered. 

Mtext Mark. Position current topic such that the line marked by “text” is 
the first line displayed. (See topic commands for a description of 
marked text.) 

Ptext text Position. Combination of .context and .mark commands. The sec- 


ond “text” string is a context looked up and immediately displayed. 
The first “text” string is a mark at which the display of the topic 


should begin. 
b Specific to Basic. 
Cc Specific to C. 
CQ.HB Used in Microsoft QuickC ® version 2.0. Indicates that the pre- 


viously viewed help topic should be redisplayed. (Executes the 
QuickC version 2.0 “Help Back” command.) This is equivalent to 
the Advisor Script Command “back” listed above, and should also 
be supported by applications requiring compatibility with C and 
QuickC help files. 


d Specific to the Microsoft CodeView® debugger. 
The command is specific to the Microsoft Editor and/or Program- 
mer’s WorkBench (PWB). The command is an editor macro string, 
which is executed. 

q Specific to the QuickHelp utility. 


2.5 Context Conventions 


Certain contexts are defined by convention across multiple product lines. The in- 
tent is that multiple products can access the same types of help in the same man- 
ner, while also providing mechanisms for truly product-specific help to be 
readily identified as such. 


Constructed context strings are kept small, to avoid unnecessary growth of the 
context string table in each help file. In addition, many utilities using the help sys- 
tem will display the context strings associated with help topics. These conven- 
tions also define characteristics which allow such utilities to present more 
intelligent information. 


2.5.1 Contexts Covered by Convention 


Context strings beginning with “x.” (where “x” is an arbitrary character, and “‘.” 
is a period) are defined to be “internal” or “constructed” help context strings. 
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They are unlikely to be explicitly requested, and you may in fact be prevented 
from entering contexts of this form. 


The following “lead” characters are defined: 


Character 


h 


2.5.2 Required Contexts 


Definition 


Generic help. Prefixes miscellaneous help contexts 
that may be constructed or otherwise hidden from 
the user. For example, a “contents” menu item 
would cause a reference to “h.contents.” 


Menu items. Contexts that relate to product menu 
items are further defined by their accelerator keys 
(for example, the Open selection on the File menu is 
referenced by “m.f.o”). 


Dialogs. Dialogs are assigned a number, and the 
help context string is constructed by “d.” and the 
ASCII text number (for example, “d.12”). 


Error numbers. Products that support the uniform 
error numbering scheme used within languages 
would reference those by prefixing the error number 
with “e.” (for example, “e.c1234”). 


Indicates a cross-reference command, as defined in 
Table 2.2. 


The following contexts should be provided in all help files: 


Context 


h.default 


h.notfound 


h.pgl 


Description 


This is the “most-default” help screen, generally dis- 
played in response to pressing F1 at the “top level” 
in most applications. 


This is the help-text applications display when a 
search for a particular context fails. Can be an index, 
topical list, or general help. Applications may alter- 
nately present error messages when help cannot be 
found. 


Indicates the help text that is logically the first 
“page” in the file. Used by some applications in re- 
sponse to a “go to the beginning” request in help 
manipulation. 
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h.pg$ Indicates the help text which is logically the last 
“page” in the file. This is used by some applications 
in response to a “go to the end” request in help 
manipulation. 


2.5.3 Recommended Contexts 


The following contexts are not mandatory, but if used, should be of the following 


defined forms: 

Context Description 

h.contents Help-file table of contents. In addition, the context 
string contents may also be used by itself to allow 
direct reference by the user. 

h.index Help-file index. In addition, the context string index 
may also be used by itself to allow direct reference 
by the user. 

h.pg# Specific page number. “#” is replaced with the page 
number of interest. 


Care should be taken to maintain “common” usage when writing help that is ref- 
erenced from context strings such as these, since other applications may access 
them in this manner. 


2.5.4 Product-Specific Contexts 


When multiple products use the same naming mechanisms for the same opera- 
tions, confusion can arise when one product help file is made available for use by 
another product. For example, search order might be the only factor determining 
which product’s help appears when a request for help is made from a File:Open 
menu and multiple product help files are available. All products would reference 
the context string “m.f.o” by convention, and it would be in both help files. 


As defined elsewhere, contexts can be prefixed by a file name. The original help- 
file file names are also embedded in each help file, and preserved regardless of 
what you rename the help file. This allows product-specific contexts to be 
dereferenced by prefixing the original help-file name to the context string. 


For example, in PWB, QB.HLP, QC.HLP, and PWB.HLP are available. All have 
a “m.f.o” context entry. When you request help on the File:Open menu, however, 
PWB prefixes that string with “pwb.hlp!”, creating “pwb.hlp!m.f.o” which com- 
pletely specifies that the help comes from the PWB help file. 
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2.6 Hierarchical Contexts 


Hierarchical context strings should be manufactured by concatenating context 
strings with period separators to form longer context strings. For example: 


cc.error.c18/6 


could represent help relating to a C compiler error number c1876. The applica- 
tion could manufacture a help look-up request based on its current state, such as 
currently viewing errors on a C compiler, where c1876 is the currently viewed 
error. 


For space reasons, it may also be advisable to shorten contexts as much as 
possible, when the context string will never be seen by the user. This is the short- 
ened example: 


c.e.1876 


It is important to note that the help engine does not infer anything from the fact 
that the context string may be viewed elsewhere as a concatenated hierarchy. 
Only a help topic whose entire context string matches exactly will correspond to 
such a request. 


2.7 Environment Support 


File names used within the help engine may include explicit path specifications 
or explicit environment variable specifications, or it may default to being opened 
on the PATH environment variable. The support for each of these is provided by 
the client application. For example: 


Path : Description 
c:\lib\qb.hlp Explicit path 
$INCLUDE:qb.hlIp Explicit environment variable 
qb.hip Implicit PATH search 


Applications may also elect to support the HELPFILES environment variable 
that specifies the help files to be used. When used, the syntax of this variable 
should be 


SAT HELPP LCESeOB snEP SC SHER SCv EP 


This example instructs applications to use the three help files, QB.HLP, 
QC.HLP, and CV.HLP, in that order. This may be overridden within the 
application. 


CHAPTER 
The HELPMAKE Program 


HELPMAKE is a general support program that manipulates help files. It can 
dump a help file to RTF text format for editing, and compress an RTF, Quick- 
Help, or modified ASCII formatted text file into help-file format. 


HELPMAKKE is a distributed utility; further documentation is available in the 

C 6.0 Compiler or Microsoft QuickC 2.0 Compiler products. Use HELPMAKE 
when you want to modify Microsoft-supplied help or to compress user-supplied 
help files. 


3.1 HELPMAKE Options 


The syntax for HELPMAKE is as follows: 


HELPMAKE { /E{n] [/Ac] [/C] [/LJ] C/N name] [/Sn] [/Wwidth] | /D[CU|S] | /H } 
C/TJ£L C/VEin]] [/Odestfile] sourcefile(s) 


At least one source file and either the “/E” (for Encode) or “/D” (for Decode) 
must be present. 


3.1.1 Encoding Options 


When encoding (/E) to create a help file, the /O parameter must be present. Mul- 
tiple source files may be specified, including wild cards. 
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The optional n parameter on /E indicates the amount of compression to take 
place. Successive powers of two indicate various compression techniques to use, 
as in the following list: 


Parameter Technique 

0 No compression 

1 Run-length compression 

Z Keyword compression 

4 Extended keyword compression 
8 Huffman compression 


For example, to use both run-length and keyword compression, specify /E3. The 
default is all compression-selected. 


Mixing the types of compression allows HELPMAKE to be maximally fast while 
developing help files, or at the user’s option when used in the field. 


3.1.2 Other HELPMAKE Options 


Other options that apply when encoding are listed below: 


Option Action 


/A Specifies the application-specific control character 
for the file. This is used with the HelpGetCells, 
HelpGetLine, and HelpGetLineAttr calls to ignore 
lines that begin with this character. This feature allows 
you to embed control information into the help topics. 
Such information can then be automatically stripped out 
by other applications without determining the format. 


IC Indicates that the context strings for this help file are 
case sensitive. All look-ups at run time are case sensi- 
tive if this switch has been set. 


[W When specified, indicates the fixed width of the result- 
ing help text, in characters. The default value is 76. 
When HELPMAKE is run to encode RTF source, 
HELPMAKE automatically formats the text to this 
width. When used with QuickHelp or Minimal ASCII, 
lines are truncated to this width. 
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fle Locks the generated file so that it cannot be decoded by 
HELPMAKE later. 
[Sn Specifies the type of input file: 
Option File Type 
1 RTF ASCII 
2 QuickHelp ASCII (default) 
3 Minimally formatted (>) ASCII 
/N Specifies a “name” or title for the help files, sub- 


sequently available to applications via the HelpGetInfo 
interface. Multiple word titles may be enclosed in 
quotes. 


/D Decodes a help file. The destination file need not be pre- 
sent, in which case the help file is decoded to standard 
output. Help files are decoded into QuickHelp ASCII 
format. 


Option Effect 


/DS “Decode split.” Splits a con- 
catenated help file back into its 
component files. No actual decod- 
ing is done, as the resulting help 
files, written to their original file 
names (as encoded in each help- 
file header) remain compressed. 


/DU “Decode unformatted.” Creates a 
plain ASCTI text file from a help 
file. All formatting information, 
such as color and cross-refer- 
encing, is lost except for .context 
statements. 


/T Translates between topic commands in “English” dot- 
command form, and the terser form. See the section in 
Chapter 2 on topic commands for more details. This 
switch is valid in both encoding and decoding. 


/H Causes HELPMAKE to display a summary of usage and 
exit. 
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CHAPTER 


Applications Interface 


The embedded help library provides the following functionality to client 
applications: 

= Help-file location and multiple file management (Open, Close) 

= Context look-up and help topic retrieval 

= Browsing functions (Next, Back) 


= Display utilities 


4.1 Defining the Interface 


The help “engine” is a library of database tools that control retrieval of text based 
on reference words (context strings), indexes (context numbers), or position. The 
applications interface is to this help engine. This section defines the help en- 
gine’s procedural interface. The engine handles the decompression of the help 


file and physical file I/O. 

Term Definition 

Convention All routines are FAR PASCAL. 

Pointers All pointers are FAR. 

“ne” type An unsigned long “context number.” All referen- 
ceable keywords or phrases (contexts) map to con- 
text numbers. A context number identifies both the 
source help file and the help context itself. 


“f” type A Boolean. 
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“PB” type A “pointer to a buffer.” In most versions of the help 
engine, this is a far pointer (void far *). In handle- 
based versions of the engine, this is a long, contain- 
ing a memory handle in the upper word, and an 
offset in the lower word. The memory handle is 
passed to HelpLock for dereferencing, and the off- 
set is then added to the result to form the actual 
physical memory address used by the help engine. 


4.2 Base File Management 
HelpOpen 


nc pascal far HelpOpen (char far *|lpszName) 
Given a help-file name, this function opens a help file and returns an initial con- 
text, or an error code on failure. Up to 25 help files can be open at a time. The ap- 


plication-provided routine OpenFileOnPath is used to open the file; typically 
that routine uses the PATH environment variable to locate the file. 


The value returned by HelpOpen, if less than HELPERR_MAX (defined in 
HELP.H), is an error code that displays the reason the file could not be opened. 


Concatenated help files count against the upper help-file limit once for each con- 
catenated portion. The initial context retumed is the context for the first physical 
topic in the help file. HelpOpen itself does not attempt to automatically append 
any extension to the file name. 


HelpClose 


void pascal far HelpClose (nc ncCur) 


Given a context, this function closes the help file associated with it and deallo- 
cates all associated memory. Calling with ncCur of zero closes all open help 
files. 


4.3 Context String Management 
HelpNe 


nc pascal far HelpNe (char far *lpszContext, nce ncInitial) 


Given a pointer to a context string, this function looks up the word and returns its 
nonzero context number. This can be used as a Boolean, returning FALSE if a 
help entry does not exist for that context string. 
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Here, ncInitial is the context from which the search for the help topic 
begins. This context references a particular help file and help topic, and the 
search commences there. 


Where concatenated help files are used and ncInitial references something 
other than the first of the concatenated files, those preceding it are not searched. 
Similarly, if ncInitial references a help context in the middle of the help 
file, those contexts preceding it will not be searched. 


The initial context returned by HelpOpen (which references the first topic in the 
file), should be saved and used for this call. 


Context strings are of the form 


[filename! ][context] 


where filename is the help file containing the cross-reference and allows 
cross-references to cross help files. The help file is located at reference time by 
using HelpOpen, and thus is located on the PATH; context is the context 
string to be referenced. If no context is present, then filename! must be pre- 
sent, and the file is assumed to be unformatted ASCII and to contain the entire 
topic. 


Context strings may also be of an internal form returned by HelpXref. See 
Help Xref in Section 4.7 for more details. 


HelpNcCmp 


nc pascal far HelpNcCmp (char far *fpszContext,nc ncInitial, 
f (pascal far *lpfnCmp) (uchar far *, 
uchar far *, ushort, f, f)); 


Like HelpNe, when given an ASCII string, this function determines the context 
number of that string. HelpNcCmp uses a caller-supplied comparison routine; 
IpfnCmp isa far pointer to the comparison routine that takes the following 
parameters: 


Parameter Description 


fpszl Far pointer to string 1. Normally the constant string 
being “looked up.” 


fpsz2 Far pointer to string 2. This is usually a string in the 
help file’s string table (compressed) or an actual seg- 
ment of the help file (formatted ASCII) being 
searched. 
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cbCmp Maximum number of bytes to compare. Normally 
the strings above are zero-terminated, and this value 
is passed as 255. In ASCII files, this value may rep- 
resent the number of bytes in the second string actu- 
ally being compared. This value can be used as a 
max comparison count, regardless of file type. 


fCase TRUE if search is to be case insensitive. This is the 
setting of the case sensitivity flag in the help file 
being processed. 

fTerm TRUE if special termination processing is allowed. 


In this case, if any white space is encountered in the 
second string when NULL is found in the first, a 
match is declared. 


HelpSzContext 


f pascal far HelpSzContext (char far *pBuffer, nc ncCur) 


Given a context and a pointer to a buffer, this function places the first context 
string associated with that help topic in the buffer and returns TRUE on success. 


The format of the string is as described for HelpNec, except that the file-name 
part is always present (but does not include any leading path). The file-name part 
references the original file name created by HELPMAKE, not the current open 
file name if the help file was renamed, or if the file was concatenated with other 
help files. 


4.4 Topic Look-Up and Decompression 
HelpNcCb 


unsigned pascal far Hel pNcCb (nc nContext) 
Given a context number, this function returns the size in bytes of the compressed 
topic. 


HelpLook 


unsigned pascal far HelpLook (nc nContext, PB pbDest) 


Given a context number, this function places the topic text into the passed buffer, 
which must be of sufficient size. HelpLook returns count of bytes in an uncom- 
pressed topic or zero on error. 
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HelpDecomp 


f pascal far HelpDecomp (PB pbTopic, PB pbDest, nc ncContext) 


Given a compressed topic as returned by HelpLook (above) and its context num- 
ber, this function decompresses it into the destination buffer. The decompressed 
text in the destination buffer is prefixed by the following topic header structure: 


typedef struct { 
uchar appchar; 
uchar linchars; 
uchar filetype; 
ushort reserved[2]; 
} topichdr; 


where uchar is defined as follows: 


Character Description 

appchar The character specified by the /A switch when the 
help file was created by HELPMAKE. 

linchar Line-removal character. Lines beginning with this 
character are ignored by the HelpGet routines de- 
scribed in Section 4.6. 

filetype The type of file that the topic came from. Values are: 
0 Unformatted ASCII 
1 Minimally formatted ASCII 
3 Fully compressed 

reserved Reserved for use by the HelpGet routines (see Sec- 
tion 4.6). 


Access to this data structure is currently present for compatibility only (see 
HelpCtl for manipulation of the ]inchar byte). HelpDecomp returns TRUE 
on error. 


4.5 Context Maneuvering 
HelpNcNext 


nc pascal far HelpNcNext (ne ncCur) 


Given a context, this function returns the context number for the next help topic, 
or NULL on catastrophic failure. 
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HelpNcPrev 


nc pascal far HelpNcPrev (nec ncCur) 


' Given a current context, this function returns the context number for the “physi- 
cally previous” help topic in the help file, or NULL on catastrophic failure. 


This function is present for those applications that present a “previous” function 
in a physical, rather than historical, manner. 


HelpNcRecord 


void pascal far HelpNcRecord (nc ncCur) 


The HelpNcRecord function records a context number in the help engine back- 
trace list. Numbers are not automatically recorded by the help engine, but must 
be explicitly recorded by client applications. This routine and HelpNcBack 
(below) maintain a Last In First Out (LIFO) list of context numbers used to main- 
tain the historical backtrace list. 


HelpNcBack 


nc pascal far HelpNcBack () 


Given a current context, this function returns the context number for the “histori- 
cally previous” help topic. These are the context numbers previously saved by 
calls to HelpNcRecord. 


HelpNcUniq 


nc pascal far HelpNcUniq (ne ncCur); 


The HelpNcUnigq function transforms a context number into a context number 
guaranteed unique for each topic in the file. That is, given that many context 
strings (and hence many context numbers) may map to the same topic, 
HelpNcUnigq transforms all the context numbers that refer to a particular topic 
into the same context number. The information on the context string originally 
used is lost. This function returns NULL on any error. 


4.6 Topic Display 


Help text returned by the help engine contains encoding information. The follow- 
ing routines are provided to aid interpretation. 


HelpGetCells 


int pascal far HelpGetCells (ushort In ,int cbMax , PB pbDst, 
uchar far *pblopic, uchar far *prgAttr) 
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HelpGetCells interprets the help file’s stored format and returns character and at- 
tribute information a line at a time. 


Character Description 

In The one-based line number to return. 

cbMax The maximum number of bytes to transfer. 

pbDst A pointer to the destination. 

pbTopic A pointer to the topic text. 

prgAttr A pointer to array of character attributes. Internal at- 
tribute indexes are mapped to physical attributes 
through this table. 


Returns number of characters transferred, or —1 if that line does not exist. 


HelpGetLine 


ushort pascal far HelpGetLine (ushort In, ushort cbMax, 
char far *pszDst, PB pbTopic); 


This function interprets the format of a topic previously read and decompressed 
and returns ASCII text a line at a time. 


The HelpGetLine function places characters into pszDst up to cbMax-I1 for the 
line specified by /n in the help topic pointed to by pbTopic. The line is zero- 
terminated and the function returns the number of characters placed in buffer. 


HelpGetLineAttr 


ushort pascal far HelpGetLineAttr (ushort In, ushort cbMax, 
LINEATTR far *rgAttrs, 
PB pbTopic); 


This function fills rgAttrs buffer with line attributes for a line defined by In. A 
line attribute is a word containing an attribute index followed by count of charac- 
ters of the attribute. 


LineAttr STRUC 
LA_attr dw fe scolor attribute 
LA_cb dw q scount of chars 
swith attribute 
LineAttr ENDS 


The array rgAtir may be terminated by an attribute of FFFF. Alternatively, if cb 
is FFFF, the attribute is used for the rest of the line. cbMax is the maximum size 
for the rgAttr buffer, and the function returns 0 if the buffer is too small for at- 
tributes; otherwise, it returns nonzero. 
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HelpcLines 
int pascal far HelpcLines (PB pbTopic); 


This function returns the number of text lines in the topic pointed to by pbTopic. 


4.7 Cross-References 
HelpXRef 


char far * pascal far HelpXRef (PB pbTopic, hotspot far *photspot) 


Given a row, column (in the hotspot structure defined below), and topic, this 
function returns a pointer to a cross-reference string. pbTopic is the pointer to the 
topic text, and photspot is a pointer to a hotspot structure to update. 


The Help XRef function returns a far pointer into the topic text of a cross-refer- 
ence string and updates the contents of the hotspot structure. It returns NULL if 
no cross-reference exists for that line. 


A “hotspot” structure defines the position of an embedded cross-reference, de- 


fined as follows: 

typedef struct { 
ushort line; /* the topic line with an xref */ 
ushort col; /* the starting column of xref */ 
ushort ecol; /* the ending column of xref */ 
uchar far *pXref; /* pointer to xref string */ 


} hotspot; 


IMPORTANT The cross-reference string can take either of two forms: a normal, null- 
terminated ASCII string, or a three-byte data structure whose first byte is NULL. It is impor- 
tant that the first byte be checked before copying the string, because normal string copy 
routines will not copy the three-byte data structure correctly. (The three-byte data structure 
is a cross-reference to a “local context.’) 


HelpHIiNext 


f pascal far HelpHiNext (int cLead, PB pbTopic, 
hotspot far *photspot); 


This function locates the next cross-reference in the help topic. Given a starting 
position in the passed hotspot structure, HelpHINext locates either the next 
physical cross-reference, or the next reference beginning with a particular charac- 
ter (case insensitive); it locates either forward or backward. 
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4.8 Utility 


One of the following can be cLead: 


NULL The next hot-link searching forward from the 
specified position is returned. 

—1 The next hot-link searching backward from the 
specified position is returned. 

char If positive and non-NULL, the next hot-link follow- 


ing the specified position whose on-screen keyword 
begins with the character cLead is returned 
(cLead must be uppercase). 


—char If negative and not —1, the next hot-link before the 
specified position whose on-screen keyword begins 
with the character -cLead is returned ( cLead 
must be uppercase). 


Here, pbTopic isa pointer to the topic text; photspot isa pointer to a hot- 
Spot structure to receive information; line and col indicate a starting point. 


The HelpHINext function returns TRUE if a cross-reference is found or if a hot- 
spot structure is updated; it returns NULL if no such cross-reference. 


HelpCt! 


void pascal far HelpCtl (PB pbTopic, flag); 


Here, pbTopic isa pointer to the topic text about to be retrieved. If the flag is 
TRUE, HelpGetLine (and family) subsequently returns all lines of text in the 
topic. If the flag is FALSE, HelpGetLine returns only those lines that do not 
begin with the application-specific control character, as specified by the /A para- 
meter to HELPMAKE when the file was compressed. (HelpGetLine “and 
family” refers to all line-retrieval, cross-reference, and line-counting routines that 
operate on the decompressed topic text.) 


NOTE HelpCtl is provided to clarify the speed-optimization behavior in these routines. The 
current method in most applications is to replace a character in the topic header (setting it 
to FF) prior to calling the line-retrieval routines, which confuses the optimization. This new 
interface hides the internal data structures that would otherwise also be modified. 
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HelpGetInfo 


int pascal far HelpGetInfo (struct helpinfo far *fpDest, 
int cbDest); 


This utility copiesa helpinfo structure relating to the specified nc to the 
specified buffer. Here, cbDest is the maximum length of the data to be copied. 
If HelpGetInfo cannot copy the data because the buffer is too small, it returns 
the required buffer size. Otherwise, it returns 0, indicating success. 


HelpInit 


void pascal far HelpInit (void) 


This call initializes data internal to the help engine. It should be called once, at 
program startup. 


NOTE This function is used only in versions of the help library that do not have pre- 
initialized data. For convenience, all libraries distributed outside of Microsoft have initialized 
data (this function is not included). 


HelpShrink 


void pascal far HelpShrink (void) 


When called, this function causes the help engine to free all memory whose data 
can be regenerated. This frees up indexes and keyword tables loaded from help 
files. The next help access can cause one or more of these tables to be reloaded. 
If there are no open help files, the engine has no memory allocated, and this call 
does nothing. 


4.9 Help Engine Callbacks 


The help engine requires some support from the application environment for file 
and memory management. 


9 


In the discussions below, “mh” is an unsigned short memory handle. “DOS only 
indicates that the call is used only in those versions of the help engine that are 
run under MS-DOS, and not in OS/2-specific versions. 


Because of the limitations of some client applications, memory management 
within the help engine is such that the engine holds no locked memory when an 
allocation is performed. 
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HelpAlloc 


mh pascal far HelpAlloc (ushort cbMem) 


This function allocates a block of memory. The memory may be movable, and 
outside of the default data segment. HelpAlloc returns NULL on failure, or if 
cbMem is 0. DOS only. 


HelpDealloc 


void pascal far HelpDealloc (mh) 


This function deallocates a block of memory. DOS only. 


HelpLock 


char far * pascal far HelpLock (mh) 


This function returns a far pointer to the base of the memory referenced by the 
handle. In the case of movable memory, the memory is also locked. If the 
memory handle passed is invalid or NULL, NULL should be returned. DOS only. 


HelpUnlock 


void pascal far HelpUnlock (mh) 


This function unlocks the memory referenced by the handle. DOS only. 


OpenFileOnPath 


fhandle pascal far OpenFileOnPath (char *fname, f fWrite); 


The file name is of the following form: 


CS$ENVVAR: | path]filename.ext 


If Then 


S$ENVVAR: is present The file does not exist in the current directory; it 
should be located on the path-formatted environ- 
ment variable specified. 


path is not present The file does not exist in the current directory; it 
should be located on the PATH environment variable. 


path is present The file is simply opened. DOS only. 
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ReadHelpFile 


ulong pascal far ReadHelpFile (int fhandle, ulong fpos, char far 
xpData, ushort cbBytes); 


ReadHelpFile reads cbBytes of data, placing it beginning at pData from 
the file whose handle is fhand/e, beginning at file offset fpos. It returns the 
number of bytes read. 


If cbBytes is zero, then the routine should return the size in bytes of the refer- 
enced file. DOS only. 


HelpCloseFile 


void pascal far HelpCloseFile (int fhandle) 


This function closes the file whose handle is passed. DOS only. 


Callback Notes 


Each call by an application to HelpOpen results in a call by the engine to 
OpenFileOnPath if the file referenced is not already open. CloseFile will not 
be called until a HelpClose operation is performed on that file. 


To reduce the number of concurrently open file handles (for applications which 
support multiple simultaneous help files), the handle returned by HelpOpen (and 
used by ReadHelpFile and CloseFile) should be a “virtual” handle. Also, some 
form of currently open file “handle caching” should be performed. By keeping 
only the most recently accessed file physically open at the DOS level, and by 
closing or opening when a request against a new virtual handle is made, the help 
system can be guaranteed to only have one file handle open at a time. 


4.10 Interface Usage 


For simple context-string-to-help-topic-text retrieval, the following steps outline 
the process. Assume that the help file has been opened via HelpOpen: 


1. Call HelpNc to get a context number for the string on which help is desired. 


2. Call HelpNcCb to determine the amount of memory required by the com- 
pressed topic. If appropriate, allocate this memory. 


3. Call HelpLook to retrieve the compressed topic from the help file. This call 
also returns the size of the uncompressed topic. If appropriate, allocate this 
memory. 
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4. Call HelpDecomp to decompress the topic text. Once completed, the 
memory for the compressed topic text may be deleted. 


5. Call HelpGetCells or HelpGetLine and HelpGetLineA ttr to extract the 
topic text and formatting information one line at a time. 


Given any valid context number returned by the help engine, you can also: 


1. Call HelpNcNext to get the context number for the next sequential topic in 
the file. 


2. Call HelpNcPrev to get the context number for the previous sequential topic 
in the file. 


3. Use HelpNcRecord and HelpNcBack to manage a history list of context 
numbers. | 


SH? OSsigmoas ica 
Exasion 


Seid 238 


7 ¢ata fixes E57 SAGOS boreaqing odrsol 
‘eae 


ss Ox my hanttteDotell bas 28 istbqlsit so disOisti@iol Iga? any) =: 


af iG — 


.¢e 


. 


aeitidesige: earn #F seencestliaih tx é 


ihe 3 


7 =r nance ee, ‘ ; = oy “fog ._. 


570 6 {8 261! se aotsnin Raranyot Dre sat i, | 
Ries eee Teas ie SyoSes ky AEDS S aie pees aft) ff “SATS ibe 
== X Sal Pe i 7 ae aes, 
Otis aaonoy niga GSA Sai Ve Sonat Gah ixches sia ea ses 
wEte 2 it oe a iss = rCatt. 
ii vigo! Tabasuped ixot sii wi aed liveiseaesnign Hshsaigvs. NE he mas 
mere Gre Das reer aif ant 
Sitar isiznonpes exciveny og} agi mein yepinesodt tag of vebaMiaisH fic 
\ PCiaGser le i sit ai 
\ 
eta ts seit -yableli a’ Sean Rare Aa gat brs brs 54H ma ig fi 
PMSA eek Sie Part ES Pa at sa Ee pay 
len. ta @ ht: 2 os 
uc DSCK Hees 
Satis ath iy Si sresoGe & | rip Saver ens ere) Sy eevee 7 
aioe ter tet Pees I: lire ‘cisrenced SINK Geer nh So eee Sines 
: ae Cesrodt sills bint ines Gestion seca fa C= IN 
a TS Sele tip eri ae of cei x oes pAaks Stasiease= Finke ape ay SS 
2 SitpTAsvi Weullespe data aresstin fies tiloss ste Dao eres ha / 3353 pentane 
\ wal du? Femi ttelgetic And taser le ana 1S 4 “hartiak sndis. Adee) ovhx 
| mae Ge sireaby meee Fle “DAs Ga a SisGigi w peois ceetis SSF ES 
WEfigent © + Porites nf Elé pinyacaaew, Onee So INE 
. ‘ryieex in 234 : 15 oa mieit at sai a => ieee ae i hendl 
eich ChG he foiaes AS le ball ase ihe . 


sic - , ; ver 
ae TE5395 HP) Car A ae : aes a. ae oe Tha et 
; + , . : 7hes me = ~ ‘ 
SCS Moola: fics (ee shel ip Skee FAS ey cies ba Sic rete re 
a ~~ - a 
: J a — 2 aol 
Ret st © .J51 We> SCEsre ab; sina a eee - 
-~ — : = 2a [= - a + AS 7 SS ws i Te 
| at i: has 4 oer ts 1? ae Tice ager CAs tise Goh ede de =) ka Deetes ee. ' 
p>, = i 2 nh a See : 4 : s 
Iie as we ib eiencnisel Tae ans ete 
' 
1 es 
2 ri 24 a . 5 7 i ash — a. ? = 4 
Sart Waal sci? 9: Vives Lea est T: tare th 53 
a = ; a ie aT Ss ew me ba: on eta tea 24 a ae ae 
= Pe iigecks 1 1S *3 Biche 24 bes SS Cuaaase heey tp tes E see O eae 


CHAPTER 
Size and Performance 


5.1 Help Engine 


The help engine itself varies in size based on functions used (and hence linked 
in) and on memory model or environment selected. In general, it ranges in size 
from 4K to 6K of code. In addition, the application requires around 4K of code to 
interface the help engine to its own environment. 


The help engine maintains 104 bytes of static data. All other data is allocated dy- 
namically, based on the number of help files being opened. For each help file 
open, 115 bytes of dynamic memory is allocated. This memory is not freed until 
the file is actually closed with the HelpClose function. Note also that concat- 
enated files count separately. That is, each concatenated portion counts as a 
single separate file. 


When accessing a help file, several tables are read in from the actual help file. 
These tables are discardable under most circumstances by calling HelpShrink. 
The tables vary in size based on the size of the help file itself. The information in 
Table 5.1 presents the relevant numbers for the file QC.HLP, a file shipped with 
QuickC 2.0, and some indication of what each is dependent on. 


At decompression time, the Keyphrase and Huffman tables must be resident in 
memory simultaneously. This is checked by the engine. In all other cases, 
HelpShrink may be called during HelpAlloc to discard unneeded or rebuildable 
memory. 


At decompression time, memory is also required for both the compressed and 
decompressed topic texts. 
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Table 5.1 QC.HLP File Information 


Type Size (in Bytes) Description 


File size 355,940 Dependent on all of the tables below, plus 
the volume of help actually provided. File 
size has no bearing on the memory require- 
ments of applications. 


Topic index 3,084 Four times the number of help topics in the 
file. QC.HLP has 771 topics. 

Context strings 4,700 Total length of all context strings supported 
by the help file. 

Context map 1,168 Two times the number of context strings 
supported. QC.HLP has 584 context strings. 

Keyphrase table 8,087 Number plus 2,048 actually allocated at 


decompression time. This table is propor- 
tional to the size of the compressible key 
phrases identified in the file at compression 
time. This is limited to 1,024 words, but the 
individual words may be of arbitrary length. 


Huffman table 1,024 Occasionally smaller than this, but in most 
cases quickly growing to this size. It is 
never larger. 


5.2 HELPMAKE. EXE 


HELPMAKE.EXE is a bound program around 60K in size. It requires 256K 
available memory to run. When compressing, it requires free disk space up to 2.5 
times the size of the input file(s). 


Glossary 


Advisor The Microsoft Advisor is the name given to the help system as actually implemented in 
many Microsoft language products. 


Application-Specific Character A character agreed upon by the applications developer and help- 
file author that signifies that the rest of the line following it is a topic command line, and not a 
line of actual help text to be displayed. Specified to HELPMAKE using the /A parameter. 


Context A keyword or phrase which is recognized by the help system and relates to a topic. 
Context Map A table which maps a context number to a topic index. 
Context Number A number in the range 1—-32,767 that uniquely identifies a context. 


Cross Reference A string associated with a “hotspot” or location in displayed help text. When 
activated, the cross-reference string may reference another help context or help file, or it may 
cause the application to take some other kind of action. 


Cross-Reference Command A context string which, when looked up by the application, usually 
in response to a hotspot selection, does not cause additional help to be retrieved. Instead it ex- 
ecutes a DOS command or causes some other application-specific action to occur. 


Dot Command English form of topic command used within QuickHelp-formatted databases. 
Executable Context See Cross-Reference Command. 
Executable Cross-Reference Command See Cross-Reference Command. 


Help Database The single compressed file output by HELPMAKE. Also, that single help file, 
when concatenated with others. 


Help File A collection of one or more help databases that constitutes a single physical file. Also, a 
single minimally formatted ASCII file. 


Help Item See Topic. 


Help Screen An application-provided window on a single topic. A help screen should be 
scrollable to allow viewing of the entire topic, should it exceed the size of a single screen. 


Hotspot The location in topic text to which a cross-reference has been attached. Hotspots are nor- 
mally highlighted in some fashion when displayed, and define areas within the displayed topic 
that activate the cross-reference when selected. 


Keyphrase A word or phrase extracted from the help text and replaced by a token during 
compression. 


Label See Context String. 


Local Context A context that has no associated context string in the help file, and is referenced 
only by a hotspot elsewhere in the same help file. 
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Node See Topic. 
Node Name See Context String. 


RTF Rich Text Format. An ASCII text format for storing documents and their formatting 
information. 


Script Topic A topic whose contents are executable cross-reference commands. 
Topic The text displayed as a help entry. May be up to 64K of encoded text. 


Topic Command A control line embedded into help text which contains control information or 
instructions for the application displaying help, as opposed to help text to be displayed. 


Topic Index A number corresponding to a sequential topic entry in the help file. Also, the table 
that maps these numbers to actual file positions. 
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